home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 17 / CU Amiga Magazine's Super CD-ROM 17 (1997)(EMAP Images)(GB)[!][issue 1997-12].iso / CUCD / Programming / DiceSource / doc / stdlib.doc < prev    next >
Text File  |  1993-07-05  |  10KB  |  472 lines
  1.  
  2.     STDLIB.DOC (c)Copyright 1990, Matthew Dillon, All Rights Reserved
  3.  
  4. TABLE OF CONTENTS
  5.  
  6. c.lib/stdlib/abs
  7. c.lib/stdlib/atexit
  8. c.lib/stdlib/atof
  9. c.lib/stdlib/atoi
  10. c.lib/stdlib/atol
  11. c.lib/stdlib/labs
  12. c.lib/stdlib/srand
  13. c.lib/stdlib/system
  14. c.lib/stdlib/qsort
  15. c.lib/stdlib/rand
  16.  
  17.  
  18. stdlib/abs                        stdlib/abs
  19. stdlib/labs                        stdlib/labs
  20.  
  21.    NAME
  22.     abs - take absolute value of int
  23.     labs- take absolute value of long
  24.  
  25.    SYNOPSIS
  26.     #include <stdio.h>
  27.     #include <stdlib.h>
  28.  
  29.     int r = [l]abs(n);
  30.     int n;
  31.  
  32.     UNDER DICE, sizeof(int) == sizeof(long) and these two functions are
  33.     thus identical.
  34.  
  35.    FUNCTION
  36.     Returns the absolute value of the specified integer.  I.E. r == n
  37.     if n >= 0, r = -n (positive) if n < 0.  Note that normally one would
  38.     not use this call due to overhead, but it exists for compatibility.
  39.  
  40.     Warning:    the absolute value of 0x80000000 cannot be taken.
  41.             0x80000000 will be returned.
  42.  
  43.    EXAMPLE
  44.     #include <stdio.h>
  45.     #include <stdlib.h>
  46.  
  47.     main()
  48.     {
  49.         int n = -53;
  50.  
  51.         printf("The absolute value of %d is %d\n", n, abs(n));
  52.         sleep(1);
  53.         printf("But its faster if you write a macro:\n");
  54.  
  55.     #define abs(x)  (((x) < 0) ? -(x) : (x))
  56.  
  57.         sleep(1);
  58.         printf("The absolute value of %d is %d\n", n, abs(n));
  59.         return(0);
  60.     }
  61.  
  62.  
  63.    INPUTS
  64.     int n;        integer
  65.  
  66.    RESULTS
  67.     int r;        absolute value of integer
  68.  
  69.    SEE ALSO
  70.  
  71.  
  72.  
  73. stdlib/atexit                        stdlib/atexit
  74.  
  75.    NAME
  76.     atexit    - specify routine that is automatically called on exit.
  77.  
  78.    SYNOPSIS
  79.     #include <stdio.h>
  80.     #include <stdlib.h>
  81.  
  82.     int error = atexit(funcptr);
  83.  
  84.     void (*funcptr)(void);
  85.  
  86.    FUNCTION
  87.     The atexit() routine adds a function to the list of functions called
  88.     when the program exits.  The atexit() routine is called before
  89.     stdio and fd's are closed down.  This exit function is called whenever
  90.     the program exits, even if main() just returns an exit code.
  91.  
  92.     atexit() will return 0 on success, -1 on failure.  Some systems limit
  93.     the number of atexit() functions one can add (DICE does not) so if
  94.     you add more than one you should check the return value.
  95.  
  96.    EXAMPLE
  97.     /*
  98.      *  atexit() is useful to free up resources that would otherwise not
  99.      *  be freed up by DICE.  For example, anything AllocMem()d.  The
  100.      *  atexit() function is called on any exit ... return from main,
  101.      *  call to exit, or ^C.
  102.      *
  103.      *  normally your atexit routine cannot make assumptions as to what
  104.      *  has been allocated and what has not since exit() can be called
  105.      *  from anywhere in the program.. things might not have been allocated
  106.      *  yet, for example.
  107.      */
  108.  
  109.     #include <stdio.h>
  110.     #include <stdlib.h>
  111.  
  112.     extern void *AllocMem();
  113.  
  114.     void *MemPtr;
  115.     long MemLen;
  116.  
  117.     void
  118.     myexit(void)
  119.     {
  120.         if (MemPtr)                 /*  only if it is allocated */
  121.         FreeMem(MemPtr, MemLen);
  122.         MemPtr = NULL;
  123.     }
  124.  
  125.     /*
  126.      *  here we can take a ^C anywhere... before we allocate, after, or
  127.      *  even after we free (note I am careful to set MemPtr back to NULL!
  128.      */
  129.  
  130.     main()
  131.     {
  132.         short i;
  133.  
  134.         atexit(myexit);
  135.         for (i = 0; i < 100; ++i)
  136.         printf("Before Alloc %d\n", i);
  137.  
  138.         MemLen = 32;
  139.         MemPtr = AllocMem(MemLen, 0);
  140.         if (MemPtr == NULL) {
  141.         puts("uh oh, AllocMem failed!");
  142.         exit(1);
  143.         }
  144.  
  145.         for (i = 0; i < 100; ++i)
  146.         printf("After Alloc %d\n", i);
  147.         FreeMem(MemPtr, MemLen);
  148.         MemPtr = NULL;    /*  must do this or atexit routine thinks */
  149.                 /*  memory is still allocated!          */
  150.  
  151.         for (i = 0; i < 100; ++i)
  152.         printf("After Free %d\n", i);
  153.  
  154.         return(0);
  155.     }
  156.  
  157.     1> avail
  158.     1> testprg
  159.       ...        (you can ^C the testprg at any point)
  160.     1> avail    (no memory loss should be seen)
  161.  
  162.  
  163.    INPUTS
  164.     void (*funcptr)(void);      routine to add to exit call list, takes
  165.                     no arguments and returns nothing.
  166.  
  167.    RESULTS
  168.     int error;            0 on success, -1 on failure.
  169.  
  170.    SEE ALSO
  171.     onbreak
  172.  
  173.  
  174. stdlib/atof                        stdlib/atof
  175.  
  176.    NAME
  177.     atof - convert string into double floating point value
  178.  
  179.    SYNOPSIS
  180.     #include <stdio.h>
  181.     #include <stdlib.h>
  182.  
  183.     double d = atof(str);
  184.     const char *str;
  185.  
  186.    FUNCTION
  187.     atof converts a string into a double floating point value, it is
  188.     equivalent to calling strtod(str, NULL).   Please refer to strtod()
  189.     for more information.
  190.  
  191.    INPUTS
  192.     char *str;    string, like "1.234E-4";
  193.  
  194.    RESULTS
  195.     double d;    double fp representation of string
  196.  
  197.    SEE ALSO
  198.     strtod
  199.  
  200.  
  201. stdlib/atoi                        stdlib/atoi
  202. stdlib/atol                        stdlib/atol
  203.  
  204.    NAME
  205.     atoi - convert string into integer
  206.     atol - convert string into long integer
  207.  
  208.    SYNOPSIS
  209.     #include <stdio.h>
  210.     #include <stdlib.h>
  211.  
  212.     int x = atoi(str);
  213.     long y = atol(str);
  214.     const char *str;
  215.  
  216.     Under DICE, sizeof(int) == sizeof(long), and thus these two routines
  217.     are exactly the same.
  218.  
  219.    FUNCTION
  220.     atoi() and atol() convert a string of a base 10 integer number into
  221.     an integer.  It skips initial white space, processes an optional
  222.     negative sign ('-'), then processes digits '0' - '9', return the
  223.     integer.
  224.  
  225.     Both atoi() and atol() are superceeded by the strtol() function which
  226.     can handle numbers of any base.  Please refer to the strtol()
  227.     manual page.
  228.  
  229.    EXAMPLE
  230.     #include <stdio.h>
  231.     #include <stdlib.h>
  232.  
  233.     main()
  234.     {
  235.         int i = atoi("  \t\t -123");
  236.         printf("i = %d (-123?)\n", i);
  237.         return(0);
  238.     }
  239.  
  240.    INPUTS
  241.     char *str;    string to convert to int
  242.  
  243.    RESULTS
  244.     int x;        integer result
  245.     long y;     integer result
  246.  
  247.    SEE ALSO
  248.     strtol
  249.  
  250. stdlib/system                        stdlib/system
  251.  
  252.    NAME
  253.     system - call system shell with command line
  254.  
  255.    SYNOPSIS
  256.     #include <stdio.h>
  257.     #include <stdlib.h>
  258.  
  259.     int r = system(buf);
  260.     const char *buf;
  261.  
  262.    FUNCTION
  263.     system() calls the system shell with the specified command line,
  264.     returning the exit code of the command or -1 if it was unable to
  265.     run the command.
  266.  
  267.     FOR PROGRAMS COMPILED UNDER 1.3, even if run in 1.4 enviroment, the
  268.     system call will not return the exit code from the command, but
  269.     return -1 if could not be run, 0 if it could.
  270.  
  271.     FOR PROGRAMS COMPILED UNDER 2.0, system() will use the 2.0 calls
  272.     and return a proper exit code when running under 2.0, and will use
  273.     Execute() if running under 1.3
  274.  
  275.    GETTING SYSTEM TO USE THE USER SHELL UNDER 2.0 (ADVANCED USERS ONLY)
  276.  
  277.     Under 2.0 system() defaults to using the boot shell (i.e. commodore
  278.     shell).  In order to have system() use the Sys_UserShell (for
  279.     example, to use WShell if you have WShell installed) you need to do
  280.     the following (usually in your main source module):
  281.  
  282.     #include <dos/dostags.h>
  283.  
  284.     int _SystemBoolTag = SYS_UserShell;
  285.  
  286.     You could also set this global to SYS_CustomShell if you like. The
  287.     default value is TAG_IGNORE from <utility/tagitem.h>.  To get even
  288.     more fancy you can also declare int _SystemBoolTagValue to modify
  289.     the data portion of the tag (default is 1).
  290.  
  291.     Alternately you can simply #include <stdlib.h>, not declare either
  292.     variable explicitly (they are extern'd in <stdlib.h>), and modify
  293.     them run-time from main().  The compiler will thus give an error if
  294.     you make a mistake in the variable names.
  295.  
  296.    EXAMPLE
  297.     #include <stdio.h>
  298.     #include <stdlib.h>
  299.  
  300.     main()
  301.     {
  302.         char buf[256];
  303.         FILE *fi;
  304.  
  305.         system("DIR >t:xx");
  306.         if (fi = fopen("t:xx", "r")) {
  307.         puts("Directory is:");
  308.         while (fgets(buf, sizeof(buf), fi))
  309.             printf("FuBarBletchPreamble: %s", buf);
  310.         fclose(fi);
  311.         remove("t:xx");
  312.         } else {
  313.         puts("Couldn't get directory!");
  314.         }
  315.         return(0);
  316.     }
  317.  
  318.    INPUTS
  319.     char *buf;    command line to run, like a normal AmigaDOS CLI
  320.             command line.
  321.  
  322.    RESULTS
  323.     int r;        return code
  324.  
  325.    SEE ALSO
  326.  
  327.  
  328. stdlib/qsort                        stdlib/qsort
  329.  
  330.    NAME
  331.     qsort  - sort an array of objects
  332.  
  333.    SYNOPSIS
  334.     #include <stdio.h>
  335.     #include <stdlib.h>
  336.  
  337.     (void) qsort(array, numElem, elemSize, compare_func)
  338.     void *array;
  339.     size_t numElem;
  340.     size_t elemSize;
  341.     int (*compare_func)(const void *arg1, const void *arg2);
  342.  
  343.    FUNCTION
  344.     qsort sorts numElem elements in an array based at 'array'.  Each
  345.     element is elemSize bytes long.  When a comparison is required,
  346.     qsort calls the passed compare_func function pointer with a
  347.     pointer to the two elements being sorted.
  348.  
  349.     DICE currently implements qsort with a simple merge sort algorithm,
  350.     using relatively slow movmem()s to avoid having to allocate much
  351.     additional storage.  Very little stack is used.  Traditional
  352.     qsort uses a stack based quick-sort algorithm that might use a
  353.     massive amount of stack.
  354.  
  355.    EXAMPLE
  356.     #include <stdio.h>
  357.     #include <stdlib.h>
  358.  
  359.     char *StrList[6] = {
  360.         "fubar",
  361.         "able",
  362.         "yum",
  363.         "quack",
  364.         "rigger",
  365.         "battle"
  366.     };
  367.  
  368.     my_comp(s1, s2)
  369.     char **s1;
  370.     char **s2;
  371.     {
  372.         return(strcmp(*s1, *s2));
  373.     }
  374.  
  375.     main()
  376.     {
  377.         short i;
  378.  
  379.         qsort(StrList, 6, sizeof(char *), my_comp);
  380.         for (i = 0; i < 6; ++i)
  381.         printf("%d %s\n", i, StrList[i]);
  382.         return(0);
  383.     }
  384.  
  385.    INPUTS
  386.     void *array;        pointer to base of array of objects
  387.  
  388.     size_t numElem;     number of elements in the array
  389.  
  390.     size_t elemSize;    Size, in bytes, of each element
  391.  
  392.     int (*compare_func)()   function pointer to compare function given
  393.                 pointers to two of the elements
  394.  
  395.    RESULTS
  396.     None
  397.  
  398.    SEE ALSO
  399.  
  400.  
  401. stdlib/rand                        stdlib/rand
  402. stdlib/srand                        stdlib/srand
  403.  
  404.    NAME
  405.     rand    - return pseudo random number
  406.     srand    - set seed for pseudo random number
  407.  
  408.    SYNOPSIS
  409.     #include <stdio.h>
  410.     #include <stdlib.h>
  411.  
  412.     int n = rand(void);
  413.     (void) srand(seed)
  414.  
  415.     unsigned int seed;
  416.  
  417.    FUNCTION
  418.     rand() returns a random number as a positive integer ranging from
  419.     0 to RAND_MAX.    RAND_MAX is defined in stdlib.h and is at least
  420.     32767.    DICE implements it as 2147483647 == 0x7FFFFFFF
  421.  
  422.     The initial seed used to generate the pseudo random sequence is 1,
  423.     but may be reinitialized to any number you desire using srand().
  424.     rand() is guarenteed to return the same sequence for the same
  425.     seed.
  426.  
  427.    EXAMPLE
  428.     #include <stdio.h>
  429.     #include <stdlib.h>
  430.  
  431.     main(ac, av)
  432.     char *av[];
  433.     {
  434.         short i;
  435.         short j;
  436.  
  437.         if (ac == 2) {
  438.         int seed = strtol(av[1], NULL, 0);
  439.         srand(seed);
  440.         printf("using seed = %d\n", seed);
  441.         } else {
  442.         puts("using seed = 1");
  443.         }
  444.         for (i = 0; i < 10; ++i) {
  445.         int n = rand();
  446.         printf("Random number: %08lx (%d)\n", n, n);
  447.         }
  448.         for (i = 0; i < 31; ++i) {
  449.         int isone = 0;
  450.         long mask = 1 << i;
  451.         for (j = 0; j < 32767; ++j) {
  452.             if (rand() & mask)
  453.             ++isone;
  454.         }
  455.         printf("bit %d %5d:%-5d (dev %d)\n", i, 32767 - isone, isone, 16384 - isone);
  456.         }
  457.         return(0);
  458.     }
  459.  
  460.    INPUTS
  461.     unsigned int seed;    An unsigned integer used to seed the
  462.                 pseudo random number generator via
  463.                 srand()
  464.  
  465.    RESULTS
  466.     int n;            returned by rand(), this number will be
  467.                 a positive integer.
  468.  
  469.    SEE ALSO
  470.  
  471.  
  472.